Closes: #23347 #27709 #27524 #27523

What I did

• Change the behavior of globals so that userGlobals and storyGlobals are separate in state.
  • userGlobals are globals set via toolbars/addons etc. These are dynamic and change-able.
  • userGlobals are initialized using initialGlobals.
  • storyGlobals are set via a .globals property on the meta or story inside *.stories.* files.
  • storyGlobals are fixed in place, and cannot be changed.
• initialGlobals is introduced as a concept.
  • These can only be set in a preview.* file. Addons can set them too.
  • initialGlobals are used to determine if a global's value should appear in the URL or not.
• globals is still available and results from shallow-merging userGlobals and storyGlobals.
• the useGlobals hook now return a third value: storyGlobals.
• decorators now receive an extra context property: storyGlobals.

• Adddon Viewport is configured slightly differently (see MIGRATION.md).
• Addon Backgrounds is configured slightly differently (see MIGRATION.md).
• Addon Themes now has an extra parameter disable, allowing the disabling of the tool per story.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

1. Create & run a sandbox
2. Visit localhost:6006/?path=/story/lib-preview-api-globals--overrides to see basics
3. Visit localhost:6006/?path=/story/addons-toolbars-globals--override to see toolbar behaviour
4. Test of the background & viewport addon (they use globals)
5. in the sandbox follow this migration:

   storybook/MIGRATION.md

   Lines 429 to 463 in 6141b5b

   	// .storybook/preview.js
   	export const parameters = {
   	backgrounds: {
   	- values: [
   	- { name: 'twitter', value: '#00aced' },
   	- { name: 'facebook', value: '#3b5998' },
   	- ],
   	+ options: {
   	+ twitter: { name: 'twitter', value: '#00aced' },
   	+ facebook: { name: 'facebook', value: '#3b5998' },
   	+ },
   	},
   	};
   	```
   	Setting an override value should now be done via a `globals` property on your component/meta or story itself:
   	```ts
   	// Button.stories.ts
   	export default {
   	component: Button,
   	globals: {
   	backgrounds: { value: 'twitter' },
   	},
   	};
   	```
   	This locks that story to the `twitter` background, it cannot be changed by the addon UI.
   	### New parameters format for addon viewport
   	> ! You need to set the feature flag `viewportStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format.
   	The `addon-viewport` addon now uses a new format for parameters. The `viewport` parameter is now an object with a `viewports` key that contains the viewport values.

6. Now test backgrounds and viewports again
   • take note that the URL should not contain the property/value when the value matches the initialGlobal
   • you should be able to setup initialGlobals in preview.ts and change the default value. example:

     export const initialGlobals = { viewport: { value: "phone" } };

7. Test the inheritance of globals by
   • setup a initialGlobal value
   • set the same global on a meta
   • set the same global on a story
   • expect to see the value set on the story
   • disable the value on the story, and expect the meta's value to be shown.
8. Test the new context values by creating a decorator:

   export const decorators = [(StoryFn, { globals, storyGlobals, userGlobals }) => {
   	console.log({ globals, storyGlobals, userGlobals });
   	return Story();
   }];

   This should show the correct info when navigating stories, and changing globals

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This pull request has been released as version 0.0.0-pr-26654-sha-49d01553. Try it out in a new sandbox by running npx storybook@0.0.0-pr-26654-sha-49d01553 sandbox or in an existing project with npx storybook@0.0.0-pr-26654-sha-49d01553 upgrade.